package com.tms.ned.controlmonitor;

import java.util.List;

import com.tms.ned.controlmonitor.adapters.ComponentAdapter;

/*
 * Licensed under the Apache License, Version 2.0;<br> 
 * 
 * You may not use this file except in compliance with the License. 
 * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless 
 * required by applicable law or agreed to in writing, software distributed under the License 
 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
 * See the License for the specific language governing permissions and limitations under the License. 
 */

/**
 * ControlMonitor: A ControlMonitor monitors components with which it is
 * registered by using ComponentAdapters to adapt a specific kind of component
 * into one that fires ComponentChangeEvents. ControlMonitors also validate each
 * registered component (if validation is provided on the ComponentAdapter)
 * every time any of the registered components change. This causes
 * ControlMonitor to be a single point of information about the dirty and valid
 * status of all registered controls.
 *
 * @author bshannon
 *
 */
public interface ControlMonitor {

	/**
	 * Registers a ComponentAdapter with the ControlMonitor, causing the control
	 * monitor to listen to changes to the adapted component.
	 *
	 * @param adapter
	 *            A ComponentAdapter for the ui component.
	 */
	public void registerComponent(ComponentAdapter adapter);

	/**
	 * Unregisters the ComponentAdapter from the ControlMonitor.
	 *
	 * @param adapter
	 *            The ComponentAdapter to unregister.
	 */
	public void unregisterComponent(ComponentAdapter adapter);

	/**
	 * Any components registered with the ControlMonitor will cause the
	 * ControlMonitor itself to throw ComponentChangeEvents when they change.
	 * Use this method to add a listener for such events.
	 *
	 * @param listener
	 *            ComponentChangeListener to receive events.
	 */
	public void addComponentChangeListener(ComponentChangeListener listener);

	/**
	 * Removes a ComponentChangeListener from the ControlMonitor.
	 *
	 * @param listener
	 *            The listener to remove.
	 */
	public void removeComponentChangeListener(ComponentChangeListener listener);

	/**
	 * Gathers up all of the registered adapters that have an invalid
	 * ValidationStatus.
	 *
	 * @return A list of ComponentAdapters that are "invalid"
	 */
	public List<ComponentAdapter> getInvalidControls();

	/**
	 * Gathers up all of the registered ComponentAdapters that are considered
	 * "dirty", (that is, the component's initial value does not match its
	 * current value).
	 *
	 * @return A list of ComponentAdapters that are dirty.
	 */
	public List<ComponentAdapter> getDirtyControls();

	/**
	 * Gathers up all of the ComponentAdapters that are registered with the
	 * ControlMonitor.
	 *
	 * @return A List of ComponentAdapters registered with ControlMonitor.
	 */
	public List<ComponentAdapter> getAllComponentAdapters();

	/**
	 * Resets all of the initial values of the registered adapted components to
	 * the current value. This does not actually change the value of the
	 * components, but it does affect the way the components are considered to
	 * be "dirty".  After calling this method, no components in the ControlMonitor
	 * should be dirty.
	 */
	public void resetInitialValuesToCurrentValues();
}
